<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Testing GeoDjango apps &mdash; Django 1.7.8.dev20150401230226 documentation</title>
    
    <link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../../',
        VERSION:     '1.7.8.dev20150401230226',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../../_static/doctools.js"></script>
    <link rel="top" title="Django 1.7.8.dev20150401230226 documentation" href="../../../index.html" />
    <link rel="up" title="GeoDjango" href="index.html" />
    <link rel="next" title="Deploying GeoDjango" href="deployment.html" />
    <link rel="prev" title="Geographic Sitemaps" href="sitemaps.html" />



 
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../../templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);
</script>


  </head>
  <body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../../index.html">Django 1.7.8.dev20150401230226 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../../index.html">Home</a>  |
        <a title="Table of contents" href="../../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../../genindex.html">Index</a>  |
        <a title="Module index" href="../../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="sitemaps.html" title="Geographic Sitemaps">previous</a>
     |
    <a href="../../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="deployment.html" title="Deploying GeoDjango">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="ref-contrib-gis-testing">
            
  <div class="section" id="s-testing-geodjango-apps">
<span id="testing-geodjango-apps"></span><h1>Testing GeoDjango apps<a class="headerlink" href="#testing-geodjango-apps" title="Permalink to this headline">¶</a></h1>
<p>Included in this documentation are some additional notes and settings
for <a class="reference internal" href="#testing-postgis"><em>PostGIS</em></a> and <a class="reference internal" href="#testing-spatialite"><em>SpatiaLite</em></a> users.</p>
<div class="section" id="s-postgis">
<span id="s-testing-postgis"></span><span id="postgis"></span><span id="testing-postgis"></span><h2>PostGIS<a class="headerlink" href="#postgis" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-settings">
<span id="settings"></span><h3>Settings<a class="headerlink" href="#settings" title="Permalink to this headline">¶</a></h3>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The settings below have sensible defaults, and shouldn&#8217;t require manual setting.</p>
</div>
<div class="section" id="s-postgis-template">
<span id="s-std:setting-POSTGIS_TEMPLATE"></span><span id="postgis-template"></span><span id="std:setting-POSTGIS_TEMPLATE"></span><h4><tt class="docutils literal"><span class="pre">POSTGIS_TEMPLATE</span></tt><a class="headerlink" href="#postgis-template" title="Permalink to this headline">¶</a></h4>
<p>This setting may be used to customize the name of the PostGIS template
database to use. It automatically defaults to <tt class="docutils literal"><span class="pre">'template_postgis'</span></tt>
(the same name used in the
<a class="reference internal" href="install/postgis.html#spatialdb-template"><em>installation documentation</em></a>).</p>
</div>
<div class="section" id="s-postgis-version">
<span id="s-std:setting-POSTGIS_VERSION"></span><span id="postgis-version"></span><span id="std:setting-POSTGIS_VERSION"></span><h4><tt class="docutils literal"><span class="pre">POSTGIS_VERSION</span></tt><a class="headerlink" href="#postgis-version" title="Permalink to this headline">¶</a></h4>
<p>When GeoDjango&#8217;s spatial backend initializes on PostGIS, it has to perform
an SQL query to determine the version in order to figure out what
features are available. Advanced users wishing to prevent this additional
query may set the version manually using a 3-tuple of integers specifying
the major, minor, and subminor version numbers for PostGIS. For example,
to configure for PostGIS 1.5.2 you would use:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">POSTGIS_VERSION</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-obtaining-sufficient-privileges">
<span id="obtaining-sufficient-privileges"></span><h3>Obtaining sufficient privileges<a class="headerlink" href="#obtaining-sufficient-privileges" title="Permalink to this headline">¶</a></h3>
<p>Depending on your configuration, this section describes several methods to
configure a database user with sufficient privileges to run tests for
GeoDjango applications on PostgreSQL. If your
<a class="reference internal" href="install/postgis.html#spatialdb-template"><em>spatial database template</em></a>
was created like in the instructions, then your testing database user
only needs to have the ability to create databases. In other configurations,
you may be required to use a database superuser.</p>
<div class="section" id="s-create-database-user">
<span id="create-database-user"></span><h4>Create database user<a class="headerlink" href="#create-database-user" title="Permalink to this headline">¶</a></h4>
<p>To make a database user with the ability to create databases, use the
following command:</p>
<div class="highlight-python"><div class="highlight"><pre>$ createuser --createdb -R -S &lt;user_name&gt;
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">-R</span> <span class="pre">-S</span></tt> flags indicate that we do not want the user to have the ability
to create additional users (roles) or to be a superuser, respectively.</p>
<p>Alternatively, you may alter an existing user&#8217;s role from the SQL shell
(assuming this is done from an existing superuser account):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">postgres</span><span class="c"># ALTER ROLE &lt;user_name&gt; CREATEDB NOSUPERUSER NOCREATEROLE;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-create-database-superuser">
<span id="create-database-superuser"></span><h4>Create database superuser<a class="headerlink" href="#create-database-superuser" title="Permalink to this headline">¶</a></h4>
<p>This may be done at the time the user is created, for example:</p>
<div class="highlight-python"><div class="highlight"><pre>$ createuser --superuser &lt;user_name&gt;
</pre></div>
</div>
<p>Or you may alter the user&#8217;s role from the SQL shell (assuming this
is done from an existing superuser account):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">postgres</span><span class="c"># ALTER ROLE &lt;user_name&gt; SUPERUSER;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-create-a-database-using-postgis-version-2">
<span id="create-a-database-using-postgis-version-2"></span><h4>Create a database using PostGIS version 2<a class="headerlink" href="#create-a-database-using-postgis-version-2" title="Permalink to this headline">¶</a></h4>
<p>When testing projects using <a class="reference internal" href="install/postgis.html#spatialdb-template91"><em>PostGIS 2</em></a>,
the test database is created using the <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">EXTENSION</span> <span class="pre">postgis</span></tt>
instruction, provided that no template <tt class="docutils literal"><span class="pre">template_postgis</span></tt> (or named
accordingly to <a class="reference internal" href="#std:setting-POSTGIS_TEMPLATE"><tt class="xref std std-setting docutils literal"><span class="pre">POSTGIS_TEMPLATE</span></tt></a>) exists in the current
database.</p>
</div>
</div>
<div class="section" id="s-windows">
<span id="windows"></span><h3>Windows<a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h3>
<p>On Windows platforms the pgAdmin III utility may also be used as
a simple way to add superuser privileges to your database user.</p>
<p>By default, the PostGIS installer on Windows includes a template
spatial database entitled <tt class="docutils literal"><span class="pre">template_postgis</span></tt>.</p>
</div>
</div>
<div class="section" id="s-spatialite">
<span id="s-testing-spatialite"></span><span id="spatialite"></span><span id="testing-spatialite"></span><h2>SpatiaLite<a class="headerlink" href="#spatialite" title="Permalink to this headline">¶</a></h2>
<p>Make sure the necessary spatial tables are created in your test spatial
database, as described in <a class="reference internal" href="install/spatialite.html#create-spatialite-db"><em>Creating a spatial database for SpatiaLite</em></a>. Then just do this:</p>
<div class="highlight-python"><div class="highlight"><pre>$ python manage.py test
</pre></div>
</div>
<div class="section" id="s-id1">
<span id="id1"></span><h3>Settings<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-spatialite-sql">
<span id="s-std:setting-SPATIALITE_SQL"></span><span id="spatialite-sql"></span><span id="std:setting-SPATIALITE_SQL"></span><h4><tt class="docutils literal"><span class="pre">SPATIALITE_SQL</span></tt><a class="headerlink" href="#spatialite-sql" title="Permalink to this headline">¶</a></h4>
<p>Only relevant when using a SpatiaLite version 2.3.</p>
<p>By default, the GeoDjango test runner looks for the <a class="reference internal" href="install/spatialite.html#create-spatialite-db"><em>file containing the
SpatiaLite database-initialization SQL code</em></a> in the
same directory where it was invoked (by default the same directory where
<tt class="docutils literal"><span class="pre">manage.py</span></tt> is located). To use a different location, add the following to
your settings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">SPATIALITE_SQL</span><span class="o">=</span><span class="s">&#39;/path/to/init_spatialite-2.3.sql&#39;</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="s-geodjango-tests">
<span id="s-id2"></span><span id="geodjango-tests"></span><span id="id2"></span><h2>GeoDjango tests<a class="headerlink" href="#geodjango-tests" title="Permalink to this headline">¶</a></h2>
<p>To have the GeoDjango tests executed when <a class="reference internal" href="../../../internals/contributing/writing-code/unit-tests.html#running-unit-tests"><em>running the Django test suite</em></a> with <tt class="docutils literal"><span class="pre">runtests.py</span></tt> all of the databases in the settings
file must be using one of the <a class="reference internal" href="db-api.html#spatial-backends"><em>spatial database backends</em></a>.</p>
<div class="section" id="s-example">
<span id="example"></span><h3>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
<p>The following is an example bare-bones settings file with spatial backends
that can be used to run the entire Django test suite, including those
in <a class="reference internal" href="index.html#module-django.contrib.gis" title="django.contrib.gis: Geographic Information System (GIS) extensions for Django"><tt class="xref py py-mod docutils literal"><span class="pre">django.contrib.gis</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">DATABASES</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s">&#39;default&#39;</span><span class="p">:</span> <span class="p">{</span>
        <span class="s">&#39;ENGINE&#39;</span><span class="p">:</span> <span class="s">&#39;django.contrib.gis.db.backends.postgis&#39;</span><span class="p">,</span>
        <span class="s">&#39;NAME&#39;</span><span class="p">:</span> <span class="s">&#39;geodjango&#39;</span><span class="p">,</span>
        <span class="s">&#39;USER&#39;</span><span class="p">:</span> <span class="s">&#39;geodjango&#39;</span><span class="p">,</span>
    <span class="p">},</span>
   <span class="s">&#39;other&#39;</span><span class="p">:</span> <span class="p">{</span>
        <span class="s">&#39;ENGINE&#39;</span><span class="p">:</span> <span class="s">&#39;django.contrib.gis.db.backends.postgis&#39;</span><span class="p">,</span>
        <span class="s">&#39;NAME&#39;</span><span class="p">:</span> <span class="s">&#39;other&#39;</span><span class="p">,</span>
        <span class="s">&#39;USER&#39;</span><span class="p">:</span> <span class="s">&#39;geodjango&#39;</span><span class="p">,</span>
   <span class="p">}</span>
<span class="p">}</span>

<span class="n">SECRET_KEY</span> <span class="o">=</span> <span class="s">&#39;django_tests_secret_key&#39;</span>
</pre></div>
</div>
<p>Assuming the settings above were in a <tt class="docutils literal"><span class="pre">postgis.py</span></tt> file in the same
directory as <tt class="docutils literal"><span class="pre">runtests.py</span></tt>, then all Django and GeoDjango tests would
be performed when executing the command:</p>
<div class="highlight-python"><div class="highlight"><pre>$ ./runtests.py --settings=postgis
</pre></div>
</div>
<p>To run only the GeoDjango test suite, specify <tt class="docutils literal"><span class="pre">django.contrib.gis</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ ./runtests.py --settings=postgis django.contrib.gis
</pre></div>
</div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../../contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Testing GeoDjango apps</a><ul>
<li><a class="reference internal" href="#postgis">PostGIS</a><ul>
<li><a class="reference internal" href="#settings">Settings</a><ul>
<li><a class="reference internal" href="#postgis-template"><tt class="docutils literal"><span class="pre">POSTGIS_TEMPLATE</span></tt></a></li>
<li><a class="reference internal" href="#postgis-version"><tt class="docutils literal"><span class="pre">POSTGIS_VERSION</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#obtaining-sufficient-privileges">Obtaining sufficient privileges</a><ul>
<li><a class="reference internal" href="#create-database-user">Create database user</a></li>
<li><a class="reference internal" href="#create-database-superuser">Create database superuser</a></li>
<li><a class="reference internal" href="#create-a-database-using-postgis-version-2">Create a database using PostGIS version 2</a></li>
</ul>
</li>
<li><a class="reference internal" href="#windows">Windows</a></li>
</ul>
</li>
<li><a class="reference internal" href="#spatialite">SpatiaLite</a><ul>
<li><a class="reference internal" href="#id1">Settings</a><ul>
<li><a class="reference internal" href="#spatialite-sql"><tt class="docutils literal"><span class="pre">SPATIALITE_SQL</span></tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#geodjango-tests">GeoDjango tests</a><ul>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h3>Browse</h3>
  <ul>
    
      <li>Prev: <a href="sitemaps.html">Geographic Sitemaps</a></li>
    
    
      <li>Next: <a href="deployment.html">Deploying GeoDjango</a></li>
    
  </ul>
  <h3>You are here:</h3>
  <ul>
      <li>
        <a href="../../../index.html">Django 1.7.8.dev20150401230226 documentation</a>
        
          <ul><li><a href="../../index.html">API Reference</a>
        
          <ul><li><a href="../index.html"><tt class="docutils literal"><span class="pre">contrib</span></tt> packages</a>
        
          <ul><li><a href="index.html">GeoDjango</a>
        
        <ul><li>Testing GeoDjango apps</li></ul>
        </li></ul></li></ul></li></ul>
      </li>
  </ul>

  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="../../../_sources/ref/contrib/gis/testing.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Apr 02, 2015</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="sitemaps.html" title="Geographic Sitemaps">previous</a>
     |
    <a href="../../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="deployment.html" title="Deploying GeoDjango">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>